ARAL Plan模块接口变更说明文档
| 修订日期 | 修订版本 | 修订内容 | 修订人 |
|---|---|---|---|
| 2026.01.27 | v0.1 | 初始化文档 | 赵锦强 |
| 2026.07.16 | v0.2 | 基于最新导出头文件更新Plan模块接口迁移关系 | 赵锦强 |
[TOC]
概述
本文档说明 robot_library_interface.hpp 中旧Plan模块接口迁移到最新导出接口后的变化情况。最新导出头文件中，原统一机器人接口中的规划能力被拆分到多个对象中：
- Task类 (
robot_task.hpp)：负责任务状态、周期、全局笛卡尔运动约束、速度缩放、同步控制、停止/恢复和周期取点。 - Planner类 (
robot_planner.hpp)：负责路径/速度/跟踪运动指令、路径预览、规划器容量、队列深度和暂停点等规划器级能力。 - State类 (
robot_state.hpp)：负责机器人状态初始化，以及关节速度/加速度限制的设置与查询。 - Model类 (
robot_model.hpp)：负责机器人模型级参数，例如功率限制。 - Scene类 (
robot_scene.hpp)：负责创建和获取Planner、Task等接口对象。
本文档以
aral_export/include/aral/*.hpp最新导出头文件为准。
接口变更列表
1. 初始化相关接口
| 功能 | 原函数 | 替代函数 | 备注 |
|---|---|---|---|
| 初始化规划器状态 | tpInitiatePlanner(q, qd, qdd, status) |
State::rsInitiateRobotState(q, qd, qdd, t_w) + Task::tskSetTaskState(...) |
tpInitiatePlanner 从0.39版本废弃；新接口由State初始化机器人状态，任务状态由Task管理。 |
| 初始化规划器状态（含工具工件） | tpInitiatePlanner(q, qd, qdd, tw, status) |
State::rsInitiateRobotState(q, qd, qdd, t_w) + Task::tskSetTaskState(...) |
最新State初始化接口固定包含 ToolWorkpiece 参数。 |
2. 状态管理相关接口
| 功能 | 原函数 | 替代函数 | 备注 |
|---|---|---|---|
| 设置规划器状态 | tpSetPlannerState |
Task::tskSetTaskState |
移至Task类，状态类型从 PlannerStatus 改为 TaskState。 |
| 清空轨迹执行队列 | tpClearExecutionQueue |
Task::tskSetTaskState(TaskState::IDEL) |
通过设置 IDEL 状态清空Task管理的规划器轨迹执行队列。 |
| 获取规划器状态 | tpGetPlannerStatus |
Task::tskGetTaskState |
移至Task类，返回类型从 int 改为 TaskState。 |
3. 周期设置相关接口
| 功能 | 原函数 | 替代函数 | 备注 |
|---|---|---|---|
| 设置规划周期 | tpSetPlannerCycle |
Task::tskSetCycle |
移至Task类。 |
| 获取规划周期 | tpGetPlannerCycle |
Task::tskGetCycle |
移至Task类。 |
4. 速度/加速度限制和动态调速相关接口
| 功能 | 原函数 | 替代函数 | 备注 |
|---|---|---|---|
| 获取笛卡尔空间最大速度 | tpGetMaximumCartesianVelocity |
Task::tskGetCartesianVelocityLimits(Array2d& cart_vel) |
移至Task类，新接口通过输出参数返回，并返回错误码。 |
| 获取笛卡尔空间最大加速度 | tpGetMaximumCartesianAcceleration |
Task::tskGetCartesianAccelerationLimits(Array2d& cart_acc) |
移至Task类，新接口通过输出参数返回，并返回错误码。 |
| 获取关节空间最大速度 | tpGetMaximumJointVelocity |
State::rsGetJointMaximumSpeed() |
关节约束由State维护。Model::mdlGetJointMaximumVelocity() 仍可查询模型级关节最大速度。 |
| 获取关节空间最大加速度 | tpGetMaximumJointAcceleration |
State::rsGetJointMaximumAcceleration() |
关节加速度约束由State维护。 |
| 设置速度和加速度限制 | tpSetVelocityAndAccelerationLimits |
Task::tskSetCartesianVelocityAccelerationLimits(...) + State::rsSetJointMaximumSpeed(...) + State::rsSetJointMaximumAcceleration(...) |
旧接口同时设置关节和笛卡尔约束；新架构中笛卡尔约束由Task管理，关节约束由State管理。 |
| 缩放速度和加速度 | tpScaleVelocityAndAcceleration |
Task::tskSetVelocityScaleFactor |
新接口仅暴露速度缩放比例，不再暴露加速度缩放参数。 |
| 获取缩放比例 | tpGetScaledFactor |
Task::tskGetVelocityScaledFactor |
新接口仅返回速度缩放比例。 |
| 缩减任务规划 | - | Task::tskReducePlan |
新增Task能力，用于按当前全局运动约束对轨迹执行队列重新规划。 |
5. 功率限制相关接口
| 功能 | 原函数 | 替代函数 | 备注 |
|---|---|---|---|
| 设置机器人功率限制 | tpSetRobotPowerLimits |
Model::mdlSetRobotPowerLimits |
迁移到Model类。 |
| 获取机器人功率限制 | tpGetRobotPowerLimits |
Model::mdlGetRobotPowerLimits |
迁移到Model类。 |
6. 容量和队列管理相关接口
| 功能 | 原函数 | 替代函数 | 备注 |
|---|---|---|---|
| 设置规划器容量 | tpSetPlannerCapacity |
Planner::tpSetPlannerCapacity |
移至Planner类，接口语义保持一致。 |
| 获取规划器容量 | tpGetPlannerCapacity |
Planner::tpGetPlannerCapacity |
移至Planner类，接口语义保持一致。 |
| 获取规划器队列深度 | tpGetPlannerDepth |
Planner::tpGetPlannerDepth |
移至Planner类，接口语义保持一致。 |
7. 运动时长相关接口
| 功能 | 原函数 | 替代函数 | 备注 |
|---|---|---|---|
| 获取指定路径段运动时长 | tpGetMoveDuration |
Planner::tpGetMoveDuration |
移至Planner类，接口语义保持一致。 |
| 获取规划器剩余运动时长 | tpGetPlannerLeftMoveDuration |
Planner::tpGetPlannerLeftMoveDuration |
规划器级剩余时长查询。 |
| 获取任务剩余运动时长 | - | Task::tskGetLeftMoveDuration |
新增任务级剩余运动时长查询。 |
8. 暂停点相关接口
| 功能 | 原函数 | 替代函数 | 备注 |
|---|---|---|---|
| 获取暂停点信息 | tpGetPausedPoint(TrajectoryPoint&, ik_eps) |
Planner::tpGetPausedPoint(TrajectoryPoint&) |
移至Planner类，移除 ik_eps 参数。 |
9. 路径点获取相关接口
| 功能 | 原函数 | 替代函数 | 备注 |
|---|---|---|---|
| 获取未来时刻的路点信息 | tpGetPathPointAtGivenTime |
Planner::tpGetPathPointAtGivenTime |
移至Planner类，接口语义保持一致。 |
| 获取路径上指定比例的路径点 | tpGetPathPointAtGivenPathLengthRatio |
Planner::tpGetPathPointAtGivenPathLengthRatio |
移至Planner类，接口语义保持一致。 |
| 按分辨率长度或规划周期预览路径点 | tpGetPathPointAtGivenResolutionLength |
Planner::tpGetPathPointAtGivenResolutionLength |
最新接口包含 vel_preview 参数；vel_preview=true 时按规划周期预览，s 参数无效。 |
10. 轨迹更新相关接口
| 功能 | 原函数 | 替代函数 | 备注 |
|---|---|---|---|
| 更新规划器状态（无输出） | tpUpdateCycle(cycle) |
已删除 | 从0.39版本废弃。 |
| 更新规划器状态并输出轨迹点 | tpUpdateCycle(cycle, TrajectoryPoint&) |
Task::tskUpdateCycle(cycle, std::vector<TrajectoryPoint>&, PlannerHandle&) |
移至Task类；支持多机器人输出，轨迹点输出改为 std::vector<TrajectoryPoint>，增加 failed_planner 用于错误定位。 |
11. 运动添加和跟踪相关接口
| 功能 | 原函数 | 替代函数 | 备注 |
|---|---|---|---|
| 目标运动跟踪（含工具工件） | tpTargetMotionTracking(..., ToolWorkpiece, ...) |
Planner::tpTargetMotionTracking(...) |
旧含 ToolWorkpiece 重载从0.40版本废弃；最新接口移至Planner类并移除 ToolWorkpiece 参数。 |
| 目标运动跟踪 | tpTargetMotionTracking |
Planner::tpTargetMotionTracking |
移至Planner类。 |
| 轨迹跟踪（含工具工件） | tpTrajectoryTracking(..., ToolWorkpiece, ...) |
Planner::tpTrajectoryTracking(...) |
旧含 ToolWorkpiece 重载从0.40版本废弃；最新接口移至Planner类并移除 ToolWorkpiece 参数。 |
| 轨迹跟踪 | tpTrajectoryTracking |
Planner::tpTrajectoryTracking |
移至Planner类。 |
| 添加直线运动（含工具工件） | tpAddPositionLine(..., ToolWorkpiece) |
Planner::tpAddPositionLine(...) |
旧含 ToolWorkpiece 重载从0.40版本废弃；最新接口移至Planner类并移除 ToolWorkpiece 参数。 |
| 添加直线运动 | tpAddPositionLine |
Planner::tpAddPositionLine |
移至Planner类；双机器人同时走 moveJ 时，可按Planner创建时的主从角色整体规划。 |
| 添加多点运动（含工具工件） | tpAddPoints(..., ToolWorkpiece) |
Planner::tpAddPoints(...) |
旧含 ToolWorkpiece 重载从0.40版本废弃；最新接口移至Planner类并移除 ToolWorkpiece 参数。 |
| 添加多点运动 | tpAddPoints |
Planner::tpAddPoints |
移至Planner类。 |
| 生成无碰撞路径（含工具工件） | tpGenerateCollisionFreePoints(..., ToolWorkpiece, out_points) |
Planner::tpGenerateCollisionFreePoints(..., out_points) |
旧含 ToolWorkpiece 重载从0.40版本废弃；最新接口移至Planner类并移除 ToolWorkpiece 参数。 |
| 生成无碰撞路径 | tpGenerateCollisionFreePoints |
Planner::tpGenerateCollisionFreePoints |
移至Planner类；最新签名包含 in_points、path_property、obstacle_avoidance_params 和 out_points。 |
| 添加速度运动（含工具工件） | tpAddVelocityLine(..., ToolWorkpiece) |
Planner::tpAddVelocityLine(...) |
旧含 ToolWorkpiece 重载从0.40版本废弃；最新接口移至Planner类并移除 ToolWorkpiece 参数。 |
| 添加速度运动 | tpAddVelocityLine |
Planner::tpAddVelocityLine |
移至Planner类。 |
12. 恢复和停止相关接口
| 功能 | 原函数 | 替代函数 | 备注 |
|---|---|---|---|
| 恢复运动（含工具工件） | tpResume(..., ToolWorkpiece) |
Planner::tpSetResumePoint(...) + Task::tskResume() |
旧含 ToolWorkpiece 重载从0.40版本废弃；恢复点由Planner设置，恢复动作由Task执行。 |
| 恢复运动 | tpResume(from, path_property, move_property) |
Planner::tpSetResumePoint(...) + Task::tskResume() |
新架构将“设置恢复起点”和“恢复任务执行”拆分；Task::tskResume() 无参数。 |
| 设置恢复点 | - | Planner::tpSetResumePoint |
新增Planner接口，用于设置恢复起始点。 |
| 停止运动 | tpStop |
Task::tskStop |
移至Task类，参数为 StopType、acc_ratio 和 buffSize。 |
| 终止交融/结束路径 | tpSetEndPath |
Planner::tpSetEndPath |
移至Planner类；用于对插入到规划器的路径进行速度规划生成轨迹段，该接口不会中断动态交融。 |
13. 同步控制相关接口（新增）
| 功能 | 原函数 | 替代函数 | 备注 |
|---|---|---|---|
| 开始定义同步运动组 | - | Task::tskWaitSyncMove |
在Task层创建一个未就绪的同步组，用于记录后续各Planner插入的同步路径ID。 |
| 完成同步运动组定义 | - | Task::tskSyncMoveOn |
收集 tskWaitSyncMove 之后各Planner新增的同步路径ID，统计各Planner同步段总时长，并按最长时长计算采样周期缩放系数。 |
同步控制不是暂停Planner自动规划后再触发统一规划，而是在 tskWaitSyncMove 与 tskSyncMoveOn 之间标记一组需要同步的路径段。tskSyncMoveOn 以该组中各Planner的路径总时长为依据，计算周期缩放比例；后续 Task::tskUpdateCycle 取点时将缩放比例下发到对应Planner，通过采样时间缩放实现同启同停的时间同步。默认情况下，不调用同步指令时，Task按普通模式取点，不进行同步组时间缩放。
14. 摆动/摆焊相关接口说明
最新 robot_planner.hpp 导出接口中未包含 tpSetWeaveParameters、tpUpdateWeaveParameters 和 tpAddWeavePath。这些接口仍可在旧统一接口 robot_library_interface.hpp 中看到：
| 功能 | 旧统一接口 | 最新Planner导出状态 | 备注 |
|---|---|---|---|
| 设置摆动参数 | tpSetWeaveParameters |
当前 Planner 导出接口未包含 |
如需继续使用或导出到Planner，应同步确认接口头文件。 |
| 更新摆动参数 | tpUpdateWeaveParameters |
当前 Planner 导出接口未包含 |
如需继续使用或导出到Planner，应同步确认接口头文件。 |
| 添加摆焊路径 | tpAddWeavePath |
当前 Planner 导出接口未包含 |
旧统一接口中仍有该声明，最新Planner头文件未导出。 |
主要变更总结
架构变化
职责拆分：原
robot_library_interface.hpp中Plan相关能力不再由单一接口承载。Task：任务状态、周期、笛卡尔速度/加速度限制、速度缩放、同步、停止/恢复和周期取点。Planner：路径添加、速度运动、目标/轨迹跟踪、路径预览、容量/队列、暂停点和恢复点。State：机器人状态初始化、关节速度/加速度限制。Model：机器人模型级参数，例如功率限制。
创建方式变化：
Planner和Task由Scene创建并管理。Scene::rlCreateRobotPlanner(...)创建Planner。Scene::rlGetRobotPlanner(...)获取Planner。Scene::rlCreateRobotTask(...)创建Task。
参数简化：大部分规划接口移除了
ToolWorkpiece参数；工具/工件相关信息由状态、模型或路径属性相关数据统一维护。多机器人支持增强：
Task::tskUpdateCycle输出std::vector<TrajectoryPoint>，可一次返回多个机器人轨迹点，并通过failed_planner定位失败的规划器。
接口命名变化
tp*前缀的旧接口按职责迁移：- 规划器级路径/跟踪/预览能力 →
Planner::tp* - 任务级状态/取点/同步/停止/恢复能力 →
Task::tsk* - 状态初始化和关节约束 →
State::rs* - 模型级功率限制 →
Model::mdl*
- 规划器级路径/跟踪/预览能力 →
功能增强
- 同步控制：新增
Task::tskWaitSyncMove和Task::tskSyncMoveOn，通过同步路径ID分组、统计各Planner同步段运动时长，并对采样周期进行缩放，实现多Planner同启同停的时间同步。 - 错误定位：
Task::tskUpdateCycle增加failed_planner输出参数，便于多机器人场景定位错误来源。 - 恢复流程拆分：通过
Planner::tpSetResumePoint设置恢复起点，再由Task::tskResume恢复执行。 - 任务级重规划：新增
Task::tskReducePlan，用于按当前全局运动约束对轨迹执行队列重新规划。
删除或不再暴露的能力
tpUpdateCycle(cycle)无输出版本从0.39版本废弃，最新接口中不再使用。- 加速度缩放参数不再由Task新接口直接暴露，仅保留速度缩放
Task::tskSetVelocityScaleFactor。 - 旧统一接口中的摆动/摆焊接口未出现在最新
robot_planner.hpp导出接口中；如需作为Planner能力使用，需要先同步确认导出头文件。